feat(sdk): expose the sandbox binding to TypeScript - #402
Open
ItamarZand88 wants to merge 1 commit into
Open
Conversation
Greptile SummaryThe PR exposes the existing Rust sandbox binding through the Node addon and TypeScript SDK while preserving lazy resolution, typed values, and explicit stream cleanup.
Confidence Score: 5/5The PR appears safe to merge. No blocking failure remains.
|
| Filename | Overview |
|---|---|
| crates/alien-bindings-node/src/sandbox.rs | Adds the thin N-API sandbox facade and an explicit, idempotent command-stream close operation that connects TypeScript iterator cleanup to backend cancellation. |
| packages/bindings/src/factories.ts | Adds lazy typed sandbox wrappers and ensures command streams are closed on normal completion and every early iterator exit. |
| packages/bindings/src/loader.ts | Defines the raw sandbox addon contract consumed by the TypeScript wrapper. |
| packages/bindings/src/types.ts | Publishes session, command-frame, command-options, capability, file, and lifecycle types for sandbox consumers. |
| packages/sdk/src/index.ts | Re-exports the sandbox factory and its public types from the application-facing SDK. |
| packages/bindings/src/tests/factories.test.ts | Verifies lazy command startup, frame streaming, early-exit cleanup, environment forwarding, and file operations. |
Sequence Diagram
sequenceDiagram
participant App as TypeScript application
participant SDK as @alienplatform/sdk
participant Wrapper as @alienplatform/bindings
participant Addon as Node N-API addon
participant Provider as Rust Sandbox provider
App->>SDK: sandbox(name)
SDK->>Wrapper: resolve lazy sandbox facade
App->>Wrapper: runCommand(session, command, options)
Wrapper->>Addon: runCommand(...)
Addon->>Provider: Sandbox::run_command(...)
Provider-->>Addon: command frame stream
loop Async iteration
Wrapper->>Addon: next()
Addon-->>Wrapper: stdout / stderr / exit frame
Wrapper-->>App: typed CommandFrame
end
App-->>Wrapper: break, return, throw, or completion
Wrapper->>Addon: close()
Addon->>Provider: drop output receiver
Reviews (18): Last reviewed commit: "feat(sdk): expose the sandbox binding to..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 11, 2026 21:22
1b99225 to
b89ff3c
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 11, 2026 21:26
b89ff3c to
52bc095
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 11, 2026 22:16
52bc095 to
28faa2f
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 11, 2026 22:24
28faa2f to
57c6f58
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 12, 2026 06:32
57c6f58 to
aa77872
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 12, 2026 06:55
aa77872 to
5a61970
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 12, 2026 07:05
5a61970 to
21baedb
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 12, 2026 07:22
21baedb to
3223ed8
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 12, 2026 07:49
3223ed8 to
adf2f66
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 12, 2026 08:11
adf2f66 to
3163375
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
2 times, most recently
from
August 12, 2026 09:15
4aec1df to
efc05a9
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 12, 2026 11:01
efc05a9 to
cdf38bb
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
2 times, most recently
from
August 12, 2026 12:14
235f3a7 to
c8dc475
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 12, 2026 13:25
c8dc475 to
ef250f2
Compare
ItamarZand88
force-pushed
the
itamar/alien-75-sandbox-6-typescript
branch
from
August 16, 2026 15:57
ef250f2 to
34bbffd
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Exposes the sandbox binding to TypeScript, so an application written in TypeScript can create a session, run a command, move files and stop it through the same contract the Rust bindings use.
When a TypeScript application asks for a sandbox binding:
create,runCommand,readFile,writeFiles,terminate.What I did
The published capability set is the interesting part. A portable application cannot assume every backend does everything — preview exists only on AWS, hostname allowlists exist nowhere, and ceilings are enforced on some platforms and refused on others. Rather than let a call fail somewhere deep in a cloud SDK, the capability set is exposed to TypeScript as data, so an application can branch before it calls.
The types are generated from the Rust definitions rather than hand-written, so the two languages cannot drift: the binding JSON is the cross-language contract.
Files touched
crates/alien-bindings-node/— the N-API surface.packages/bindings/src/types.ts— the generated binding types.packages/sdk/src/index.ts— the public export.How I tested
packages/bindings/tests/sandbox.test.ts— the binding shape and the capability set as TypeScript sees them.pnpm generate— confirms the committed types match the Rust definitions; CI fails the build if they drift.